Stack
=================

沿一个新轴对输入张量序列进行堆叠。所有输入张量必须具有相同的形状。

.. math::

   \text{若输入 } num\_inputs \text{ 个形状为 } (d_0, d_1, \dots, d_{n-1}) \text{ 的张量，并在 } axis \text{ 处堆叠：}

.. math::

   output\_shape = (d_0, \dots, d_{axis-1}, num\_inputs, d_{axis}, \dots, d_{n-1})

输入：
    - **inputs** - 指针数组，包含所有输入张量起始地址的数组。
    - **input_shape** - 所有输入张量共用的形状（shape）数组。
    - **num_inputs** - 输入张量的数量。
    - **axis** - 堆叠操作插入新维度的位置。
    - **input_ndim** - 输入张量的维度数（秩）。
    - **core_mask(int, 可选)** - 核掩码（仅适用于共享存储版本）。

输出：
    - **output** - 计算结果存储地址。

支持平台：
    ``FT78NE``  
    ``MT7004``

.. note::
    - FT78NE 支持 int8, int16, int32, fp32, fp64, cplx64, cplx128
    - MT7004 支持 fp16, fp32, int16, int32, cplx64
    - 所有输入张量必须具有完全一致的 `input_shape`。
    - 输出张量的维度将比输入张量多 1。

**共享存储版本:**

.. c:function:: void i8_stack_s(int8_t* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, int8_t* output, int core_mask)
.. c:function:: void i16_stack_s(int16_t* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, int16_t* output, int core_mask)
.. c:function:: void i32_stack_s(int32_t* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, int32_t* output, int core_mask)
.. c:function:: void hp_stack_s(half* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, half* output, int core_mask)
.. c:function:: void fp_stack_s(float* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, float* output, int core_mask)
.. c:function:: void dp_stack_s(double* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, double* output, int core_mask)
.. c:function:: void c64_stack_s(float* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, float* output, int core_mask)
.. c:function:: void c128_stack_s(double* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, double* output, int core_mask)

    **C调用示例：**

    .. code-block:: c
        :linenos:
        :emphasize-lines: 20

        // FT78NE 示例（共享存储）
        #include <stdio.h>
        #include "78NE/utils.h"

        int main() {
            // 输入形状为 {4, 10, 8, 12}
            int input_shape[] = { 4, 10, 8, 12 };
            int input_ndim = 4;
            int num_inputs = 3;
            int axis = 1;
            int core_mask = 0b1011;

            float *in0 = (float *)0xA0000000;
            float *in1 = (float *)0xA2000000;
            float *in2 = (float *)0xA4000000;
            float *inputs[] = { in0, in1, in2 };
            float *output = (float *)0xB0000000; 
            // 输出形状将变为 {4, 3, 10, 8, 12}

            fp_stack_s(inputs, input_shape, num_inputs, axis, input_ndim, output, core_mask);
            return 0;
        }


**私有存储版本:**

.. c:function:: void i8_stack_p(int8_t* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, int8_t* output)
.. c:function:: void i16_stack_p(int16_t* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, int16_t* output)
.. c:function:: void i32_stack_p(int32_t* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, int32_t* output)
.. c:function:: void hp_stack_p(half* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, half* output)
.. c:function:: void fp_stack_p(float* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, float* output)
.. c:function:: void dp_stack_p(double* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, double* output)
.. c:function:: void c64_stack_p(float* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, float* output)
.. c:function:: void c128_stack_p(double* inputs[], int* input_shape, int num_inputs, int axis, int input_ndim, double* output)

    **C调用示例：**

    .. code-block:: c
        :linenos:
        :emphasize-lines: 15

        // MT7004 示例（私有存储）
        #include <stdio.h>

        int main() {
            int input_shape[] = { 2, 3, 4, 5 };
            int input_ndim = 4;
            int num_inputs = 2;
            int axis = 0;

            float *in0 = (float *)0x10810000; 
            float *in1 = (float *)0x10812000; 
            float *inputs[] = { in0, in1 };
            float *output = (float *)0x10820000;

            fp_stack_p(inputs, input_shape, num_inputs, axis, input_ndim, output);
            return 0;
        }